/***
 * Copyright 2002-2010 jamod development team
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 ***/

package net.wimpi.modbus.util;

/**
 * A simple non-reentrant mutual exclusion lock. The lock is free upon
 * construction. Each acquire gets the lock, and each release frees it.
 * Releasing a lock that is already free has no effect.
 * <p/>
 * This implementation makes no attempt to provide any fairness or ordering
 * guarantees. If you need them, consider using one of the Semaphore
 * implementations as a locking mechanism.
 * <p/>
 * <b>Sample usage</b><br>
 * <p/>
 * Mutex can be useful in constructions that cannot be expressed using java
 * synchronized blocks because the acquire/release pairs do not occur in the
 * same method or code block. For example, you can use them for hand-over-hand
 * locking across the nodes of a linked list. This allows extremely fine-grained
 * locking, and so increases potential concurrency, at the cost of additional
 * complexity and overhead that would normally make this worthwhile only in
 * cases of extreme contention.
 * 
 * <pre>
 * class Node {
 *   Object item;
 *   Node next;
 *   Mutex lock = new Mutex(); // each node keeps its own lock
 * <p/>
 *   Node(Object x, Node n) { item = x; next = n; }
 * }
 * <p/>
 * class List {
 *    protected Node head; // pointer to first node of list
 * <p/>
 *    // Use plain java synchronization to protect head field.
 *    //  (We could instead use a Mutex here too but there is no
 *    //  reason to do so.)
 *    protected synchronized Node getHead() { return head; }
 * <p/>
 *    boolean search(Object x) throws InterruptedException {
 *      Node p = getHead();
 *      if (p == null) return false;
 * <p/>
 *      //  (This could be made more compact, but for clarity of illustration,
 *      //  all of the cases that can arise are handled separately.)
 * <p/>
 *      p.lock.acquire();              // Prime loop by acquiring first lock.
 *                                     //    (If the acquire fails due to
 *                                     //    interrupt, the method will throw
 *                                     //    InterruptedException now,
 *                                     //    so there is no need for any
 *                                     //    further cleanup.)
 *      for (;;) {
 *        if (x.equals(p.item)) {
 *          p.lock.release();          // release current before return
 *          return true;
 *        }
 *        else {
 *          Node nextp = p.next;
 *          if (nextp == null) {
 *            p.lock.release();       // release final lock that was held
 *            return false;
 *          }
 *          else {
 *            try {
 *              nextp.lock.acquire(); // get next lock before releasing current
 *            }
 *            catch (InterruptedException ex) {
 *              p.lock.release();    // also release current if acquire fails
 *              throw ex;
 *            }
 *            p.lock.release();      // release old lock now that new one held
 *            p = nextp;
 *          }
 *        }
 *      }
 *    }
 * <p/>
 *    synchronized void add(Object x) { // simple prepend
 *      // The use of `synchronized'  here protects only head field.
 *      // The method does not need to wait out other traversers
 *      // who have already made it past head.
 * <p/>
 *      head = new Node(x, head);
 *    }
 * <p/>
 *    // ...  other similar traversal and update methods ...
 * }
 *
 * @author Doug Lea
 * @version @version@ (@date@)
 */
public class Mutex {

	/**
	 * The lock status
	 */
	protected boolean inuse_ = false;

	public void acquire() throws InterruptedException {
		if (Thread.interrupted())
			throw new InterruptedException();
		synchronized (this) {
			try {
				while (inuse_)
					wait();
				inuse_ = true;
			} catch (InterruptedException ex) {
				notify();
				throw ex;
			}
		}
	}// accquire

	public synchronized void release() {
		inuse_ = false;
		notify();
	}// release

	public boolean attempt(long msecs) throws InterruptedException {
		if (Thread.interrupted())
			throw new InterruptedException();
		synchronized (this) {
			if (!inuse_) {
				inuse_ = true;
				return true;
			} else if (msecs <= 0)
				return false;
			else {
				long waitTime = msecs;
				long start = System.currentTimeMillis();
				try {
					for (;;) {
						wait(waitTime);
						if (!inuse_) {
							inuse_ = true;
							return true;
						} else {
							waitTime = msecs
									- (System.currentTimeMillis() - start);
							if (waitTime <= 0)
								return false;
						}
					}
				} catch (InterruptedException ex) {
					notify();
					throw ex;
				}
			}
		}
	}// attempt

}// class Mutex